package module.StoreService;

import common.model.Entity.StoreEntity.CartItem;
import network.protocol.Response;

import java.util.List;
import java.util.Optional;

/**
 * {@code CartItemService} 定义了购物车项相关的业务操作接口。
 * <p>
 * 提供对购物车项的增删改查以及统计功能，包括：
 * <ul>
 *     <li>根据购物车 ID 查询购物车项</li>
 *     <li>根据购物车 ID 和商品 ID 获取特定购物车项</li>
 *     <li>添加、更新或删除购物车项</li>
 *     <li>获取购物车项数量和总金额</li>
 * </ul>
 * <p>
 * 所有方法返回统一封装的 {@link Response} 对象，
 * 以便在调用时处理成功或失败的响应。
 */
public interface CartItemService {

    /**
     * 根据购物车 ID 获取购物车中的所有购物车项。
     *
     * @param cartId 购物车的唯一标识
     * @return 包含购物车项列表的响应对象；
     *         如果购物车为空，则返回空列表
     */
    Response<List<CartItem>> getCartItemsByCartId(long cartId);

    /**
     * 根据购物车 ID 和产品 ID 获取指定的购物车项。
     *
     * @param cartId    购物车的唯一标识
     * @param productId 产品的唯一标识
     * @return 包含指定购物车项的响应对象；
     *         如果不存在则返回 {@link Optional#empty()}
     */
    Response<Optional<CartItem>> getCartItemByCartAndProduct(long cartId, long productId);

    /**
     * 将商品添加到购物车中。
     * <p>
     * 如果购物车中已存在该商品，则可能需要叠加数量；
     * 如果不存在，则新增一条购物车项。
     *
     * @param cartId    购物车的唯一标识
     * @param productId 产品的唯一标识
     * @param quantity  添加的数量，必须大于零
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> addToCart(long cartId, long productId, int quantity);

    /**
     * 更新购物车项中的商品数量。
     *
     * @param cartItemId 购物车项的唯一标识
     * @param quantity   更新后的数量，必须大于零
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateCartItemQuantity(long cartItemId, int quantity);

    /**
     * 从购物车中删除指定的购物车项。
     *
     * @param cartItemId 购物车项的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> removeFromCart(long cartItemId);

    /**
     * 获取购物车中的商品项数量。
     *
     * @param cartId 购物车的唯一标识
     * @return 包含购物车项数量的响应对象
     */
    Response<Integer> getCartItemCount(long cartId);

    /**
     * 计算购物车中所有商品的总金额。
     *
     * @param cartId 购物车的唯一标识
     * @return 包含购物车总金额的响应对象
     */
    Response<Double> getCartTotalAmount(long cartId);
}
